클로드 코드 완벽 가이드 — 3장 클로드 코드 환경 설정 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

전체 흐름도 (ASCII 다이어그램)

[환경 설정 시작]
       |
       v
+------------------+     +------------------+     +------------------+
| OS 확인           |     | 선행 소프트웨어   |     | 클로드 코드 설치  |
|                  |     |                  |     |                  |
| macOS → 직접 설치 |     | 1. Node.js 설치  |     | npm install -g   |
| Windows → WSL   |---->| 2. npm 설치      |---->| @anthropic-ai/   |
|   필수 (리눅스)   |     |                  |     |   claude-code    |
|                  |     | 버전 확인:       |     |                  |
+------------------+     | node --version   |     | 설치 확인:       |
                         | npm --version    |     | claude 실행      |
                         +------------------+     +------------------+
                                                         |
                                                         v
                                              +------------------+
                                              | 첫 실행 & 인증   |
                                              |                  |
                                              | 1. 폴더 신뢰 확인|
                                              |    Yes, proceed  |
                                              | 2. 로그인 선택   |
                                              |    구독 or API    |
                                              | 3. 프롬프트 창   |
                                              |    사용 시작!     |
                                              +------------------+

선수 지식 체크리스트

• [ ] 2장: 클로드 코드 요금제 이해 (Pro/Max/API 차이)
• [ ] 터미널(CLI) 기본 조작 (명령어 입력, 디렉터리 이동)
• [ ] Node.js와 npm이 무엇인지 기본 개념
• [ ] macOS와 Windows의 차이점 기본 이해
• [ ] WSL(Windows Subsystem for Linux)이 무엇인지 대략적 개념

핵심 키워드

3.1 핵심 철학 — 기존 워크플로를 건드리지 않는다

한 줄 요약

클로드 코드는 기존 개발 환경을 방해하지 않고 보완하는 도구이며, 초기 설정만 잘 해두면 원래 도구처럼 자연스럽게 스며든다.

쉬운 설명 (비유로 풀어쓰기)

클로드 코드를 개발 환경에 추가하는 것은 책상 위에 새 스탠드 조명을 놓는 것과 같다. 기존에 쓰던 모니터, 키보드, 마우스를 바꾸는 게 아니라, 있던 환경 그대로 두고 조명 하나만 추가해서 작업이 더 편해지는 것이다. VSCode를 쓰고 있었다면 VSCode를 그대로 쓰면 되고, IntelliJ를 쓰고 있었다면 IntelliJ를 그대로 쓰면 된다.

핵심 원칙:

실무 예제

❌ 잘못된 접근: "클로드 코드를 설치했으니 VSCode를 버리고 터미널만 써야 하나?"
✅ 올바른 접근: "VSCode는 그대로 쓰면서, 터미널 탭에서 claude를 실행해 보조로 활용한다"

❌ 잘못된 접근: "새로운 개발 방식을 처음부터 배워야 하나?"
✅ 올바른 접근: "평소 쓰던 대로 개발하되, 필요할 때 claude에게 도움을 요청한다"

체크포인트

• [ ] 클로드 코드가 기존 IDE를 대체하는 것이 아님을 이해했는가?
• [ ] 초기 설정의 목적이 "자연스러운 통합"임을 이해했는가?

3.2 macOS 환경 설정

한 줄 요약

macOS에서는 Node.js 공식 사이트에서 설치 패키지를 받고, npm으로 클로드 코드를 전역 설치한 뒤 claude 명령어로 실행한다.

쉬운 설명 (비유로 풀어쓰기)

macOS에 클로드 코드를 설치하는 과정은 새 앱 3단계 설치와 같다. 먼저 앱 스토어(Node.js 사이트)에서 기반 프로그램을 받고(1단계), 그 프로그램의 설치 도구(npm)로 클로드 코드를 설치하고(2단계), 터미널에서 claude를 입력해 실행한다(3단계). 마치 게임을 하려면 먼저 스팀(Steam)을 깔고, 스팀에서 게임을 다운받고, 게임을 실행하는 것과 같은 흐름이다.

실무 예제 — 설치 순서

1단계: Node.js 설치

# nodejs.org/ko/download 접속 후 macOS Installer (.pkg) 다운로드
# 패키지 실행 → Continue 클릭 → 설치 완료

# 설치 확인
node --version    # v22.17.1 같은 버전이 출력되면 성공!
npm --version     # 10.9.2 같은 버전이 출력되면 성공!

2단계: 클로드 코드 설치

npm install -g @anthropic-ai/claude-code

3단계: 실행 확인

claude
# 프롬프트 창이 뜨면 성공!

❌ 실패 사례: node --version 입력 시 "command not found" → Node.js 설치가 안 된 것
✅ 성공 확인: node --version 입력 시 "v22.17.1" 같은 버전 번호 출력

❌ 실패 사례: npm install 시 권한 오류 발생
✅ 해결 방법: sudo npm install -g @anthropic-ai/claude-code (관리자 권한 사용)

체크포인트

• [ ] Node.js와 npm이 정상적으로 설치되었는가? (버전 확인)
• [ ] npm install -g @anthropic-ai/claude-code 명령어를 실행했는가?
• [ ] claude 명령어 입력 시 프롬프트 창이 나타나는가?

3.3 Windows 환경 설정 — WSL 필수

한 줄 요약

Windows에서 클로드 코드는 직접 실행되지 않으므로, WSL(Windows Subsystem for Linux)을 먼저 설치한 뒤 리눅스 환경에서 Node.js와 클로드 코드를 설치한다.

쉬운 설명 (비유로 풀어쓰기)

Windows에서 클로드 코드를 쓰는 것은 Windows 안에 작은 리눅스 컴퓨터를 하나 만드는 것과 같다. 클로드 코드가 리눅스에서만 돌아가기 때문에, WSL이라는 도구로 Windows 안에 리눅스 방을 하나 만들고, 그 방 안에서 설치와 실행을 진행한다. 마치 Windows에서 안드로이드 앱을 쓰려면 에뮬레이터를 깔아야 하는 것과 비슷한 원리다.

실무 예제 — 설치 순서

1단계: WSL 설치 (파워셸 관리자 권한)

wsl --install
# 설치 완료 후 반드시 컴퓨터 재시작!

2단계: WSL 실행 & 초기 설정

# 재시작 후 자동으로 Ubuntu 설치 진행
# 리눅스 계정 이름과 비밀번호 입력
# ⚠️ 비밀번호 입력 시 화면에 글자가 표시되지 않음 — 정상!

# 파워셸에서 WSL 실행
cd \
wsl --update
wsl -d ubuntu

3단계: Node.js 설치 (nvm 사용)

# nvm 다운로드 및 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Node.js 설치
nvm install 22

# 버전 확인
node -v    # "v22.17.1" 출력되면 성공
npm -v     # "10.9.2" 출력되면 성공

4단계: 클로드 코드 설치 & 실행

npm install -g @anthropic-ai/claude-code
claude    # 프롬프트 창이 뜨면 성공!

❌ 잘못된 접근: Windows PowerShell에서 바로 npm install -g @anthropic-ai/claude-code 실행
✅ 올바른 접근: 반드시 WSL(리눅스 환경) 안에서 설치 명령어 실행

❌ 흔한 실수: wsl -d ubuntu 실행 시 C:\Windows\system32에서 실행 → 경로 오류 가능
✅ 올바른 접근: cd \ 로 C:\ 루트로 이동한 뒤 wsl -d ubuntu 실행

❌ 당황 포인트: 비밀번호 입력 시 화면에 아무것도 안 보임
✅ 정상 동작: 리눅스에서 비밀번호는 보안상 화면에 표시하지 않음. 그냥 입력하면 됨

macOS vs Windows 설치 비교

체크포인트

• [ ] WSL이 정상적으로 설치되었는가? (wsl -d ubuntu 실행 가능)
• [ ] WSL 안에서 Node.js와 npm 버전이 확인되는가?
• [ ] WSL 안에서 claude 명령어가 정상 실행되는가?

3.4 첫 실행 — 폴더 신뢰 확인과 로그인

한 줄 요약

클로드 코드를 처음 실행하면 폴더 접근 권한을 확인하고, 로그인 방식(구독 vs API)을 선택한 뒤 프롬프트 창이 나타나면 설정 완료다.

쉬운 설명 (비유로 풀어쓰기)

클로드 코드를 처음 실행하는 것은 새 집에 처음 입주하는 것과 같다. 먼저 "이 집(폴더)에 들어가도 되나요?"라고 확인을 받고(폴더 신뢰), 그 다음 "열쇠를 어떤 걸로 쓸 건가요?"를 정하고(로그인 방식), 열쇠를 받으면 집에 들어가서 자유롭게 작업할 수 있다(프롬프트 창).

실무 예제

폴더 신뢰 확인:

Do you trust the files in this folder?
/Users/jihochoi/Desktop

> 1. Yes, proceed    ← 이것을 선택
  2. No, exit

로그인 방식 선택:

Select login method:
> 1. Claude account with subscription     ← 구독자 (Pro/Max)
     Starting at $20/mo for Pro, $100/mo for Max

  2. Anthropic Console account             ← API 사용자
     API usage billing

❌ 잘못된 선택: 폴더 신뢰에서 "No, exit" → 클로드 코드가 종료됨
✅ 올바른 선택: "Yes, proceed" → 정상 진행

❌ 글자가 깨져 보일 때: 터미널 글꼴이 특수문자를 지원하지 않는 경우
✅ 해결 방법: 파워셸 속성에서 글꼴을 바꿔보세요 (Consolas, D2Coding 등)

체크포인트

• [ ] 폴더 신뢰 확인에서 "Yes, proceed"를 선택했는가?
• [ ] 로그인 방식을 올바르게 선택했는가? (구독자 → 1번, API → 2번)
• [ ] 프롬프트 입력 창(>)이 나타나는가?

3.5 설치 후 유용한 팁

한 줄 요약

설치 후 /init으로 CLAUDE.md를 생성하고, /terminal-setup으로 터미널 단축키를 설정하면 더 편리하게 사용할 수 있다.

실무 예제

클로드 코드 첫 실행 시 안내되는 팁들:

Tips for getting started:
1. Run /init to create a CLAUDE.md file with instructions for Claude
2. Run /terminal-setup to set up terminal integration
3. Use Claude to help with file analysis, editing, bash commands and git
4. Be as specific as you would with another engineer for the best results

❌ 그냥 바로 사용 시작: 프로젝트 맥락 없이 질문 → 정확도 낮음
✅ /init 먼저 실행: CLAUDE.md 생성 → 프로젝트 규칙을 클로드가 인식 → 더 정확한 답변

체크포인트

• [ ] /init 명령어의 역할(CLAUDE.md 생성)을 이해했는가?
• [ ] /terminal-setup의 역할(터미널 통합 설정)을 이해했는가?

연습문제

문제 1 (기본)

macOS에서 클로드 코드를 설치하기 위해 먼저 설치해야 하는 소프트웨어 2가지는 무엇인가?

문제 2 (중급)

Windows에서 클로드 코드를 설치할 때 WSL이 필요한 이유는 무엇이며, WSL 설치 후 흔히 발생하는 경로 문제를 어떻게 해결하는가?

문제 3 (심화)

macOS와 Windows에서 Node.js 설치 방식이 다른 이유를 설명하고, Windows(WSL)에서 nvm을 사용하는 장점을 서술하시오.

문제 4 (실습)

자신의 OS에 맞는 방법으로 클로드 코드를 설치하고, claude 명령어로 실행한 뒤 폴더 신뢰 확인과 로그인까지 완료하시오. 각 단계에서 확인한 버전 정보를 기록하시오.

부록 A: 용어 사전

부록 B: 비교표

macOS vs Windows 설치 과정 비교

Node.js 설치 방식 비교

로그인 방식 비교

부록 C: 참고 자료